Org-mode: Dynamic block

Pour ajouter un bloc dynamique à un document Org-mode, on peut procéder de 2 façons:

• L'écrire sois-même
• Demander à Emacs d'écrire automatiquement le bloc

Pour la première option, on écrit simplement ceci:

#+BEGIN type-de-bloc

#+END

Les balises #+BEGIN et #+END indiquent le début et la fin du bloc. Il faut remplacer type-de-bloc par le type de bloc qu'on souhaite. On écrit rien entre les balises car c'est là que le contenu généré dynamiquement sera écrit.

Pour demander à Emacs d'ajouter le bloc au lieu de l'écrire sois-même, on peut appeler la fonction org-dynamic-block-insert-dblock (raccourcis clavier C-c C-x x). Emacs demandera le nom du type de bloc qu'on souhaite utiliser et il insérera un exemple de ce bloc.

Pour générer le contenue du bloc, il faut placer le curseur d'écriture sur la ligne #+BEGIN et appeler la fonction org-dblock-update (raccourcis clavier C-c C-c).

Tout ce qui se trouve entre le #+BEGIN et le #+END sera effacé et le texte généré y sera inséré.

Il est possible de définir des paramètres pour le bloc, sur la même ligne que la balise #+BEGIN, sous cette forme:

#+BEGIN type-de-bloc :parametre_1 11 :parametre_2 42

#+END

Dans cette exemple, on a 2 paramètres: parametre_1 qui a pour valeur 11 et parametre_2 qui a pour valeur 42.

Je commence par écrire une fonction Emacs-lisp comme celle-ci:

(defun org-dblock-write:example (params)
  (let ((text (plist-get params :text)))
    (insert text)))

Le nom de cette fonction à pour préfixe org-dblock-write: et accepte un seul paramètre d'entrée: params. Le nom du type de bloc est écrit dans le nom de la fonction, après le préfixe. Le paramètre est une plist dans laquelle on retrouve tous les paramètres du bloc. On peut accéder à ces paramètres avec la fonction (plist-get).

Le code de cette fonction est simple: On stock le contenu du paramètre :text dans la variable locale text. Puis on passe le contenu de cette variable à la fonction (insert). Le texte sera automatiquement inséré à l'intérieur de notre bloc dynamique au moment où son contenu sera généré.

On peut maintenant demander à Emacs d'évaluer cette nouvelle fonction.

Elle pourrait être plus simple pour ce qu'on en fait ici. Mais cette exemple, où on utilise une variable locale, est également un bon point de départ si tu souhaite faire un type de bloc plus complexe.

Maintenant, on peut utiliser le nouveau type de bloc dans un document Org-mode. Mais on doit écrire sois-même les balises #+BEGIN et #+END ainsi que le nom du bloc comme ceci:

#+BEGIN: example :text "Ceci est un test"

#+END

Ici, on précise que le type de bloc est example et on lui donne le paramètre :text avec pour valeur "Ceci est un test".

Maintenant, si on génère le contenu du bloc avec org-dblock-update (raccourcis C-c C-c), voici ce qu'on obtient:

#+BEGIN: example :text "Ceci est un test"
Ceci est un test
#+END

Ça fonctionne. Simple et efficace.

On a un nouveau type de bloc, mais si on veut l'utiliser on doit écrire les balises sois-même. La prochaine étape est d'automatiser l'écriture du bloc, par Emacs.

Et pour ça, on va simplement écrire et évaluer une fonction Emacs-lisp interactive. Cette fonction va insérer un exemple de bloc, utilisant notre nouveau type, là où se trouve le curseur d'écriture.

Voici le code de cette fonction:

(defun org-example-insert-dblock ()
  "Create a dynamic block that show an example text"
  (interactive)
  (org-create-dblock
   (list :name "example"
         :text "Un autre example à insérer")))

Elle va appeler une autre fonction: (org-create-dblock). Cette autre fonction accepte comme paramètre une plist, indiquant toutes les propriétés utilisées pour créer le bloc. Ici on précise 2 paramètres: :name est le nom du type de bloc et :text est le paramètre :text du bloc. On indique la valeur de :text comme étant la chaine de caractère "Un autre example à insérer".

Comme cette nouvelle fonction est interactive, on peut l'appeler avec le raccourcis M-x. Si on essaye dans un document Org-mode, voici le résultat qui sera inséré:

#+BEGIN: example :text "Un autre example à insérer"

#+END:

Notre bloc de type example, avec un paramètre :text déjà définit.

À noter que dans notre exemple, la fonction (org-example-insert-dblock) définit la valeur de :text de façon statique. Mais on peut aussi définir n'importe quel paramètre du bloc de façon dynamique.

Maintenant qu'on a une fonction pouvant insérer un bloc de type example, il faut dire à Emacs qu'il peut la proposer quand on appelle org-dynamic-block-insert-dblock.

Pour ça, il suffit d'écrire et d'évaluer le code Emacs-lisp suivant:

(org-dynamic-block-define "example" 'org-example-insert-dblock)

L'appelle à la fonction (org-dynamic-block-define) va associer le nom example avec la fonction org-example-insert-block.

Maintenant si, dans un document Org-mode, on appelle org-dynamic-block-insert-dblock (raccourcis C-c C-x x) et qu'on lui indique le type de bloc example, voici ce qui sera inséré:

#+BEGIN: example :text "Un autre example à insérer"

#+END: